doc(proposal): un/break `--test` by JakobJingleheimer · Pull Request #13 · nodejs/test-runner

JakobJingleheimer · 2026-02-01T12:53:58Z

A follow-up to the discussion in the 26 Jan 2026 team meeting

Ethan-Arrowood · 2026-02-02T13:59:54Z

proposals/proposal - unbreak test cli arg.md

+node
+  --test ./src/foo/*.test.js
+  --test ./src/bar/*.test.js
+  ./src/not-pjson-main.js


What would the purpose of this be? The test runner runs for the two glob patterns and then does what with this entry point script? Executes it as a test too or just as a regular node script?

Ah, yes, true. Let's say there is no such thing as an entry-point for test mode (I think that doesn't exist currently either). If there's any "entry-point" when --test is present, throw.

I think in order to run an arbitrary script, it should be done with --import (and friends); otherwise, you get into inception.

node --import ./test/env.setup.js --import ./test/fix-snapshot-naming.js --test ./src/foo/*.test.js --test ./src/bar/*.test.js

Ethan-Arrowood · 2026-02-02T14:01:04Z

proposals/proposal - unbreak test cli arg.md

+  ./src/not-pjson-main.js
+```
+
+An explicit entrypoint, like all node commands, must come last and must be a relative or absolute path (not a glob/pattern).


I don't think this tracks for test. Many users will only want to pass a single glob pattern; at least I know that I do! What would the explicit entry point do for a test script?

Ah, okay, fair. So when watch mode is combined with test mode, shall we say that entry-point is not applicable—it's only applicable for watch mode separately?

cjihrig · 2026-02-09T19:01:41Z

How will this work across versions? Please don't underestimate the pain that inconsistencies in the test runner CLI across versions cause for users (ie glob support). It takes years for these pain points to go away.

JakobJingleheimer · 2026-02-09T19:03:54Z

@cjihrig we discussed in today's meeting. I'm about to update this with the 3rd option that was born from that. I'll ping you for review in a few minutes.

cjihrig · 2026-02-09T19:29:04Z

Discussed with @JakobJingleheimer and apparently it will not break existing users, so 👍

JakobJingleheimer · 2026-02-09T19:29:31Z

I think "option 3" will actually JustWork? --test is eager/hungry, so

node
  --test ./foo.test.js
  --test ./bar.test.js

currently results in:

[
  './foo.test.js',
  '--test',
  './bar.test.js',
]

--test is nonsense for a value, and it currently gets discarded (all flags after --test do).

We can backport support for --watch-path (that’s nonbreaking); it would just continue to not work in older versions if supplied after --test.

Ethan-Arrowood

I'm still seeing some parts of this talking about main entrypoints with the test runner which just doesn't make sense. I'd prefer we clean that up before merging this as that may only cause more confusion in further discussions.

proposals/proposal - unbreak test cli arg.md

Ethan-Arrowood · 2026-02-10T17:32:58Z

proposals/proposal - unbreak test cli arg.md

+`test` would then work the same way:
+
+```sh title='reads "main" etc from package.json'
+node --test
+```
+```sh title='package.json "main" + an additional path'
+node --test ./src/**/*.test.js
+```
+```sh title='explicit entrypoint + an additional path'
+node
+  --test ./src/foo/*.test.js
+  --test ./src/bar/*.test.js
+  ./src/not-pjson-main.js


this section still needs to be updated, no? Test runs don't use main entrypoint or any entrypoint for that matter. It uses file patterns matching test files.

Ethan-Arrowood · 2026-02-10T17:34:56Z

proposals/proposal - unbreak test cli arg.md

+  --watch
+  ./src/not-pjson-main.js


I don't believe an newline character would change the CLI parsing here. This is the same as specifying a path for --watch. Or am I mistaken?

JakobJingleheimer · 2026-02-10T17:56:24Z

I'm still seeing some parts of this talking about main entrypoints with the test runner which just doesn't make sense. I'd prefer we clean that up before merging this as that may only cause more confusion in further discussions.

Are you talking about the other options besides the one added yesterday? If so, my plan was to wait for people to weigh in; once one is selected, update the proposal to move the discard ones to a new "Rejected" section, and outdent the selected option.

If you're talking about the small bit mentioning --watch's value being discarded, doesn't that align with what you just said?

…ncluding defaults plus extras

Ethan-Arrowood · 2026-02-17T21:39:15Z

Maybe I'm not tracking; I am just confused by a script like:

node --watch ./src/not-pjson-main.js --test ./test/*.test.js

Like test mode should "overrule" the watch mode here. Unless the expectation is for that example to actually favor the watch entrypoint over test entries.

Take --watch out of the example for a moment. When you run node --test you don't invoke the package.json main script. Similarly, if you specified something like:

node main.js --test test.js

Only main.js is executed and the --test test.js is ignored.

So i want to be clear in our examples of what the behavior of combining --watch with --test is. IMO this is like a special case of "Test and Watch" that is distinct from just "Watch" or just "Test" modes.

I hope I'm making sense. Kinda difficult to explain I guess

Ethan-Arrowood · 2026-02-17T21:43:53Z

Maybe my confusion / concern is that I'm conflating node --watch main.js to mean that not only is it watching main.js, but also executing it.

When you use --watch with --test, the paths specified are no longer being executed; instead it is just paths that need to be added to the watcher that would reinvoke the test process.

Thus we should be careful about language like "main entrypoint" because that implies its going to be executed (at least thats how I interpret it). I recognize that another interpretation is the main entrypoint is the default watch path.

Yeah this is a confusing one.

ljharb · 2026-02-17T23:02:08Z

node --watch works. which implies that node --watch path/to/file is the same as node --path/to/file in watch mode.

In other words, node --watch ./src/not-pjson-main.js --test ./test/*.test.js should either be executing the file in watch mode, and then running the tests in watch mode - or, be an error - --watch should be treated as a boolean flag, not something that takes an argument.

doc(proposal): un/break --test

86af8d6

JakobJingleheimer requested a review from a team February 1, 2026 12:53

JakobJingleheimer added this to Test Runner Board Feb 1, 2026

JakobJingleheimer added the test_runner-agenda label Feb 1, 2026

MoLow approved these changes Feb 1, 2026

View reviewed changes

atlowChemi approved these changes Feb 1, 2026

View reviewed changes

Ethan-Arrowood reviewed Feb 2, 2026

View reviewed changes

openjs-meetings-bot bot mentioned this pull request Feb 3, 2026

Node.js Test Runner Meeting 2026-02-09 #14

Open

add "option 3"

f34de60

JakobJingleheimer requested review from Ethan-Arrowood, ljharb and pmarchini February 9, 2026 19:19

Ethan-Arrowood reviewed Feb 10, 2026

View reviewed changes

remove entrypoint from places that don't make sense, add item for i…

fea8e41

…ncluding defaults plus extras

openjs-meetings-bot bot mentioned this pull request Feb 17, 2026

Node.js Test Runner Meeting 2026-02-23 #16

Open

Ethan-Arrowood approved these changes Feb 17, 2026

View reviewed changes

Uh oh!

Conversation

JakobJingleheimer commented Feb 1, 2026

Uh oh!

Ethan-Arrowood Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

JakobJingleheimer Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Ethan-Arrowood Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

JakobJingleheimer Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

cjihrig commented Feb 9, 2026

Uh oh!

JakobJingleheimer commented Feb 9, 2026

Uh oh!

cjihrig commented Feb 9, 2026

Uh oh!

JakobJingleheimer commented Feb 9, 2026

Uh oh!

Ethan-Arrowood left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Ethan-Arrowood Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Ethan-Arrowood Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

JakobJingleheimer commented Feb 10, 2026

Uh oh!

Ethan-Arrowood commented Feb 17, 2026

Uh oh!

Ethan-Arrowood commented Feb 17, 2026

Uh oh!

ljharb commented Feb 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants